/*
 * Copyright 2005 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.subshell.lucene.indexaccess;

import java.io.IOException;
import java.util.Set;

import org.apache.lucene.index.IndexReader;
import org.apache.lucene.index.IndexWriter;
import org.apache.lucene.search.Searcher;
import org.apache.lucene.search.Similarity;
import org.apache.lucene.store.Directory;

/**
 * <p>
 * Provides high-level index access synchronization.
 * <p>
 * 
 * <p>
 * General use is as follows:
 * <p>
 * 
 * <p>
 * 
 * <pre>
 *     ILuceneIndexAccessor accessor = ...
 * 
 *     IndexWriter writer = null;
 *     try {
 *         writer = accessor.getWriter();
 *     
 *         // use writer
 *     } catch (IOException e) {
 *         // ...
 *     } finally {
 *         accessor.release(writer);
 *     }
 * </pre>
 * 
 * </p>
 * 
 * <p>
 * After construction, an ILuceneIndexAccessor is closed, and must be
 * <code>open()</code>ed to make it usable. When done using it (at program
 * exit, for example), it must be <code>close()</code>d to release any cached
 * resources.
 * </p>
 * 
 * @author Maik Schreiber (blizzy AT blizzy DOT de)
 */
public interface ILuceneIndexAccessor {

    /**
     * Returns an IndexReader.
     * 
     * @param write
     *            Is this IndexReader to be used for write access?
     * @return IndexReader An index reader.
     * @throws IOException
     *             If there is an error getting the reader.
     */
    IndexReader getReader(boolean write) throws IOException;

    /**
     * Returns an IndexWriter.
     * 
     * @return An index writer.
     * @throws IOException
     *             If there is an error getting the writer.
     */
    IndexWriter getWriter() throws IOException;

    /**
     * Returns a Searcher. It will use default similarity.
     * 
     * @return An index searcher.
     * @throws IOException
     *             If there is an error getting the searcher.
     */
    Searcher getSearcher() throws IOException;

    /**
     * Returns a Searcher using the specified Similarity.
     * 
     * @param similarity
     *            Use this similarity.
     * @return Searcher The searcher.
     * @throws IOException
     *             If there is an error getting the searcher.
     */
    Searcher getSearcher(Similarity similarity) throws IOException;

    /**
     * Returns a Searcher using the specified Similarity and underlying
     * searchers.
     *
     * @param similarity
     *            Use this similarity.
     * @param underlyingSearchers
     *            The underlying searcher.
     * @return Searcher The searcher.
     * @throws IOException
     *             If there is an error getting the searcher.
     */
    Searcher getSearcher(Similarity similarity, Set underlyingSearchers)
            throws IOException;

    /**
     * Releases an IndexReader.
     *
     * @param reader
     *            Release the index reader.
     * @param write
     *            Has this IndexReader been opened for write access?
     */
    void release(IndexReader reader, boolean write);

    /**
     * Releases an IndexWriter.
     * 
     * @param writer
     *            Release the writer.
     */
    void release(IndexWriter writer);

    /**
     * Releases a Searcher.
     * 
     * @param searcher
     *            Release the searcher.
     */
    void release(Searcher searcher);

    /**
     * Releases a Directory.
     * 
     * @param directory
     *            Release this directory.
     * @param write
     *            Has this Directory been opened for write access?
     */
    void release(Directory directory, boolean write);

    /**
     * Close this ILuceneIndexAccessor and releases any cached resources.
     */
    void close();

    /**
     * Opens this ILuceneIndexAccessor (again) and makes it ready for use.
     */
    void open();

    /**
     * Returns whether this ILuceneIndexAccessor is opened and ready for use.
     * 
     * @return <code>true</code> if the accessor is open.
     */
    boolean isOpen();

    /**
     * Adds an index access event listener.
     * 
     * @param listener
     *            Add a listener.
     */
    void addListener(ILuceneIndexAccessListener listener);

    /**
     * Removes an index access event listener.
     * 
     * @param listener
     *            The listener to remove.
     */
    void removeListener(ILuceneIndexAccessListener listener);
}

